JBoss.orgCommunity Documentation
In Mobicents SIP Presence Apache log4j
is used for logging. If you are not familiar with the log4j package and would like to use it in your applications, you can read more about it at the Jakarta web site.
Logging is controlled from a central conf/jboss-log4j.xml
file in each server configuration profile. This file defines a set of appenders specifying the log files, what categories of messages should go there, the message format and the level of filtering. By default, Mobicents produces output to both the console and a log file (log/server.log
).
There are 6 basic log levels used: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.
Logging is organized into categories and appenders. Appenders control the destination of log entries. Different appenders differ in configuration, however each supports thresholds. Threshold filters log entries based on their level. A threshold set to WARN will allow log entries to pass into the appender if the level is WARN, ERROR or FATAL. Other entries will be discarded. For more details on appender configuration, please refer to its documentation or java doc.
The logging threshold on the console is INFO by default. However, there is no threshold set for the server.log file, so all generated logging messages are logged there.
Categories control the level for loggers and its children. For details, please refer to the log4j manual.
By default, Mobicents SIP Presence inherits a level of INFO from the root logger. To make the platform add more detailed logs, the conf/jboss-log4j.xml
file has to be altered. Explicit category definition for Mobicents SIP Presence looks like:
<category name="org.mobicents.slee">
<priority value="INFO"/>
</category>
This limits the level of logging to INFO for all Mobicents SIP Presence classes. It is possible to declare more categories with different levels, to provide logs with greater detail.
For instance, to provide detailed information on the Mobicents SIP Presence transaction engine in a separate log file (txmanager.log
), the conf/jboss-log4j.xml
file should contain entries as follows:
<appender name="TXMANAGER" class="org.jboss.logging.appender.RollingFileAppender">
<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
<param name="File" value="${jboss.server.home.dir}/log/txmanager.log"/>
<param name="Append" value="false"/>
<param name="MaxFileSize" value="500KB"/>
<param name="MaxBackupIndex" value="1"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
</layout>
</appender>
<category name="org.mobicents.slee.runtime.transaction">
<priority value="DEBUG" />
<appender-ref ref="TXMANAGER"/>
</category>
This creates a new file appender and specifies that it should be used by the logger (or category) for the package org.mobicents.slee.runtime.transaction.
The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is txmanager.log. Older files have the date they were written added to their filenames.
Besides manual logging configuration, described previously, Mobicents SIP Presence also exposes management operations that greatly simplify such configuration, allowing the administrator to select from predefined and complete logging configuration presets. These operations are available in the org.mobicents.slee%3Aservice%3DMobicentsManagement
MBean. The available presets are:
Regular logging, at INFO level, displaying most user-related messages;
More verbose logging, mostly using DEBUG/TRACE level, displaying message of interest for developers;
Low verbosity and async logging, mostly in WARN level, for systems in production so that logging does impact performance.
The available management operations are:
Retrieves the current logging configuration;
Allows switching between configuration presets;
Used to upload a complete logging configuration.
Custom presets can be easily deployed in the application server too. Simply name the configuration file as jboss-log4j.xml.PRESET_NAME
, where PRESET_NAME
should be a unique preset name, and copy it into the $JBOSS_HOME/server/profile_name/deploy/mobicents-slee/log4j-templates
directory, where profile_name is the server profile name.
These procedures change the whole platform logging configuration, so it will also affect logging for other running applications besides the SIP Presence elements.
Notification sources such as SBBs, Resource Adaptors, Profiles, and SLEE internal components use the JAIN SLEE Trace Facility
to generate trace messages intended for consumption by external management clients. Management clients register to receive trace messages generated by the Trace Facility
through the external management interface (MBean). Filters can be applied in a similar way to Alarms.
Within the SLEE, notification sources use a tracer
to emit trace messages. A tracer is a named entity. Tracer names are case-sensitive and follow the Java hierarchical naming conventions. A tracer is considered to be an ancestor of another tracer if its name followed by a dot is a prefix of the descendant tracer’s name. A tracer is considered to be a parent of a tracer if there are no ancestors between itself and the descendant tracer. For example, the tracer named com
is the parent tracer of the tracer named com.foo
and an ancestor of the tracer named com.foo.bar
.
All tracers are implicitly associated with a notification source, which identifies the object in the SLEE that is emitting the trace message, and is included in trace notifications generated by the Trace MBean
on behalf of the tracer. For instance, an SBB notification source is composed by the SBB ID and the Service ID.
Multiple notification sources may have tracers with same name in SLEE. Comparing with common logging frameworks, this would mean that the notification source would be part of the log category or name.
For further information on how to use JAIN SLEE Trace Facility
and receive JMX notifications refer to the JAIN SLEE 1.1 Specification.
Mobicents SIP Presence Tracers additionally log messages to Apache Log4j, being the log4j category, for notification source X
, defined as javax.slee.
concatenated with the X.toString()
.
For instance, the full log4j logger name
for tracer named GoogleTalkBotSbb
, of sbb notification source with SbbID[name=GoogleTalkBotSbb,vendor=mobicents,version=1.0]
and ServiceID[name=GoogleTalkBotService,vendor=mobicents,version=1.0]
, would be javax.slee.SbbNotification[service=ServiceID[name=GoogleTalkBotService, vendor=mobicents,version=0.1], sbb=SbbID[name=GoogleTalkBotSbb,vendor=mobicents, version=0.1]].GoogleTalkBotSbb
(without the spaces or breaks), which means a log4j category defining its level as DEBUG
could be:
<category
name="javax.slee.SbbNotification[service=ServiceID[name=GoogleTalkBotService,
vendor=mobicents,version=0.1],sbb=SbbID[name=GoogleTalkBotSbb,
vendor=mobicents,version=0.1]]">
<priority value="DEBUG" />
</category>
The relation of JAIN SLEE tracers
and log4j loggers
goes beyond log4j showing tracer's messages. Changing the tracer's log4j logger effective level
changes the tracer level in SLEE, and vice-versa. Since JAIN SLEE tracer levels differ from log4j logger levels, the table below maps the two:
Table 7.1. Mapping JAIN SLEE Tracer Levels with Apache Log4j Logger Levels
Tracer Level | Logger Level |
---|---|
OFF | OFF |
SEVERE | ERROR |
WARNING | WARN |
INFO | INFO |
CONFIG | INFO |
FINE | DEBUG |
FINER | DEBUG |
FINEST | TRACE |